================================================================================
PART 1: General Introduction & Basic Operations of "Mathtols:ResolveFormula"
================================================================================

1.1. OVERVIEW
--------------------------------------------------------------------------------

In e following Text we will call "Mathtols:ResolveFormula" in short "evaluator".
The "evaluator" is a powerful mathematical and logical expression parser. 
It takes a string containing a formula, such as "SIN(30) + 5*2", and returns a precise
numeric result, a string result, or a descriptive error message.
Besidess that it has Special featues for Binary calculations using Strings.

It is designed to be a self-contained tool with a rich set of built-in
operators, constants, and functions, covering everything from basic arithmetic
to advanced statistics, unit conversions, and bitwise logic.
Currently it can not make internal loops


1.2. BASIC USAGE
--------------------------------------------------------------------------------
The MathTools_ResolveFormula function has two parameters:

1. formula (Required, string)
The mathematical expression to evaluate (e.g., "2 + 2 * 3", "sin(pi/2)").

2. options (Optional, string)
A string of flags to modify behavior:

"r" – Enables rounding (applies to numeric results).
"#" – Switches trigonometric functions (sin, cos, tan) to degree mode (default is radians).
Example with options:

MathTools_ResolveFormula(formula="sin(90)", options="#") → Returns 1 (since 90° = π/2 radians).


The primary function to call is `Mathtols:ResolveFormula`.

Example:
  Eval("5+3", 0)  --> Returns "CVE:" + MKE$(8)
  Eval("HEX(10)", 0) --> Returns "RES:&HA"
  Eval("5/0", 0)    --> Returns "ERR:Division by zero."


1.3. NUMBER FORMATS
--------------------------------------------------------------------------------

The evaluator supports several number formats within the expression string.

- Standard Decimal:
  Includes integers and floating-point numbers.
  Samples:
    123
    -45.67
    .5

- Scientific Notation (E-notation):
  For very large or very small numbers.
  Samples:
    6.022E23
    1E-9
    -2.5E+10

- Hexadecimal (&H prefix):
  Base-16 numbers. Digits are 0-9 and A-F. The value is converted to a 64-bit
  integer.
  Samples:
    &HFF          (evaluates to 255)
    &H100         (evaluates to 256)
    &HCAFE        (evaluates to 51966)

- Octal (&O prefix):
  Base-8 numbers. Digits are 0-7. The value is converted to a 64-bit integer.
  Samples:
    &O77          (evaluates to 63)
    &O100         (evaluates to 64)

- Binary (&B prefix):
  Base-2 numbers. Digits are 0 and 1. The value is converted to a 64-bit
  integer.
  Samples:
    &B1010        (evaluates to 10)
    &B11111111    (evaluates to 255)


1.4. BASIC ARITHMETIC OPERATORS
--------------------------------------------------------------------------------

The evaluator supports standard arithmetic operations. Parentheses `()` can be
used to override the default order of operations.

- Addition (+):
  Sample: 5 + 3.2         --> 8.2

- Subtraction (-):
  Sample: 10 - 4          --> 6

- Multiplication (*):
  Sample: 7 * 6           --> 42

- Division (/):
  Sample: 100 / 8         --> 12.5

- Integer Division (\):
  Discards the remainder.
  Sample: 100 \ 8         --> 12

- Exponentiation (^ or **):
  Raises a number to a power.
  Sample: 2 ^ 10          --> 1024
  Sample: 3 ** 4          --> 81

- Modulo (MOD):
  Returns the remainder of an integer division.
  Sample: 10 MOD 3        --> 1


================================================================================
PART 2: Complete Operator Reference & Built-in Constants
================================================================================

2.1. OPERATOR PRECEDENCE
--------------------------------------------------------------------------------

Operators are evaluated in a specific order. The following list is ordered from
highest precedence (evaluated first) to lowest.

1.  Postfix operators (!, Unit Conversions)
2.  Exponentiation (^)
3.  Unary Sign (+, -), Prefix NOT
4.  Multiplication, Division (*, /, \)
5.  Modulo (MOD)
6.  Addition, Subtraction (+, -)
7.  Relational Operators (=, <>, >, <, >=, <=)
8.  Logical AND
9.  Logical OR, XOR
10. Logical EQV, IMP

You can always use parentheses `()` to force a specific order of evaluation.

Sample:
  5 + 2 * 10        --> 25 (multiplication is done first)
  (5 + 2) * 10      --> 70 (parentheses force addition first)


2.2. COMPLETE OPERATOR LIST
--------------------------------------------------------------------------------

--- Arithmetic Operators ---
  +      Addition
  -      Subtraction
  * Multiplication
  /      Floating-point division
  \      Integer division
  ^, ** Exponentiation
  MOD    Modulo (integer remainder)

--- Relational Operators ---
  (Return -1 for TRUE, 0 for FALSE)
  =      Equal to
  <>     Not equal to
  !=     Not equal to (alias for <>)
  ><     Not equal to (alias for <>)
  >      Greater than
  <      Less than
  >=     Greater than or equal to
  =>     Greater than or equal to (alias for >=)
  <=     Less than or equal to
  =<     Less than or equal to (alias for <=)
  Samples:
    5 > 3             --> -1 (TRUE)
    10 = 10           --> -1 (TRUE)
    10 = 9            -->  0 (FALSE)
    (2+2) <> 4        -->  0 (FALSE)

--- Logical (Boolean) Operators ---
  (Operate on TRUE (-1) and FALSE (0) values)
  AND    Logical AND
  OR     Logical OR
  XOR    Logical Exclusive OR
  NOT    Logical NOT (prefix unary operator)
  EQV    Logical Equivalence
  IMP    Logical Implication
  Samples:
    -1 AND 0          --> 0 (FALSE)
    -1 OR 0           --> -1 (TRUE)
    NOT 0             --> -1 (TRUE)
    NOT (5 > 3)       --> 0 (FALSE)

--- Postfix Operators ---
  !      Factorial. Must follow a non-negative integer.
  Sample: 5!              --> 120


2.3. BUILT-IN CONSTANTS
--------------------------------------------------------------------------------

You can use the following named constants directly in your expressions. They are
case-insensitive.

--- Mathematical Constants ---
  PI# or PI         The value of Pi (~3.14159)
  E# or E           The value of Euler's number (~2.71828)

--- Physics & Astronomy Constants ---
  (Values are in standard SI units unless otherwise specified)
  - Acceleration_of_gravity
  - Alpha_particle_mass
  - Atomic_mass_constant
  - Avogadro
  - Boltzmann
  - Dry_air_density_at_STP
  - Earth_equatorial_radius
  - Earth_escape_velcity
  - Earth_magnetic_dipole_moment
  - Earth_mass
  - Earth_mean_angular_rotational_speed
  - Earth_mean_density
  - Earth_mean_orbital_speed
  - Earth_polar_radius
  - Earth_volume
  - Electron_charge-mass_ratio
  - Electron_rest_mass
  - Elementary_charge
  - Faraday_constant
  - Gravitational_constant
  - Light_speed_in_a_vacuum
  - Muon_rest_mass
  - Neutron_rest_mass
  - Permeability_constant
  - Permittivity_constant
  - Planck_constant
  - Proton_rest_mass
  - Rydberg_constant
  - Solar_constant
  - Sound_speed_at_STP
  - Standard_atmosphere
  - Stefan-Boltzmann_constant
  - Universal_gas_constant
  - Wien_displacement_constant

Sample:
  2 * PI * 10                   --> 62.83185...
  Light_speed_in_a_vacuum / 2   --> 149896229


================================================================================
PART 3: Comprehensive Function Library
================================================================================

Functions are called using their name followed by parentheses containing one or
more arguments, separated by commas. Example: `MAX(10, 20, 30)`.

3.1. TRIGONOMETRIC & HYPERBOLIC FUNCTIONS
--------------------------------------------------------------------------------

These functions are affected by the `angleMode` parameter of the `Eval` function.
You can also use the `DEGREES()` and `RADIANS()` conversion functions.

--- Standard Trigonometric ---
  SIN(x), COS(x), TAN(x)
  SEC(x), CSC(x), COT(x)

--- Inverse Trigonometric ---
  ATN(x) or ARCTAN(x)     - Arctangent
  ATAN2(y, x) or ATN2(y,x) - Arctangent of y/x, returning correct quadrant
  ARCSIN(x), ARCCOS(x)
  ARCSEC(x), ARCCSC(x), ARCCOT(x)

--- Hyperbolic ---
  SINH(x), COSH(x), TANH(x)
  SECH(x), CSCH(x), COTH(x)

--- Inverse Hyperbolic ---
  ARCSINH(x), ARCCOSH(x), ARCTANH(x)
  ARCSECH(x), ARCCSCH(x), ARCCOTH(x)

Samples:
  SIN(RADIANS(30))        --> 0.5
  DEGREES(ATN(1))         --> 45
  COSH(0)                 --> 1


3.2. LOGARITHMIC & EXPONENTIAL FUNCTIONS
--------------------------------------------------------------------------------

  EXP(x)            - e raised to the power of x
  LOG(x) or LN(x)   - Natural logarithm (base e)
  LOG(x, base)      - Logarithm of x to a specified base
  CLG(x) or LOG10(x)- Common logarithm (base 10)
  TLG(x) or LOG2(x) - Binary logarithm (base 2)
  ETO(x) or EXP2(x) - 2 raised to the power of x
  ETE(x) or EXP10(x)- 10 raised to the power of x
  POW(x, y)         - x raised to the power of y (same as x^y)
  SQR(x) or SQRT(x) - Square root of x

Samples:
  LOG(100, 10)            --> 2
  CLG(1000)               --> 3
  POW(2, 8)               --> 256
  SQR(64)                 --> 8


3.3. NUMERIC, ROUNDING & NUMBER THEORY
--------------------------------------------------------------------------------

  ABS(x)            - Absolute value of x
  SGN(x)            - Sign of x (-1 for negative, 0 for zero, 1 for positive)
  CEIL(x)           - Rounds up to the nearest integer
  FLOOR(x)          - Rounds down to the nearest integer
  FIX(x)            - Truncates the decimal part
  FRAC(x)           - Returns the fractional part
  ROUND(x, places)  - Rounds x to a specified number of decimal places
  RND()             - Returns a random number between 0 and 1
  RND(x)            - Returns a random number between 0 and x
  GCD(a, b)         - Greatest Common Divisor
  LCM(a, b)         - Least Common Multiple
  ISPRIME(n)        - Returns -1 (TRUE) if n is prime, 0 (FALSE) otherwise

Samples:
  ABS(-10.5)              --> 10.5
  CEIL(4.1)               --> 5
  FLOOR(4.9)              --> 4
  ROUND(3.14159, 2)       --> 3.14
  GCD(48, 18)             --> 6


3.4. STATISTICAL FUNCTIONS (VARIADIC)
--------------------------------------------------------------------------------

These functions can take one or more arguments.

  COUNT(...)        - Counts the number of arguments
  SUM(...)          - Sum of all arguments
  AVERAGE(...)      - Average (mean) of all arguments
  MAX(...)          - The largest value among the arguments
  MIN(...)          - The smallest value among the arguments
  VAR(...) or
  STDEV(...)        - Sample standard deviation
  VARP(...) or
  STDEVP(...)       - Population standard deviation

Samples:
  MAX(10, 50, -20)        --> 50
  SUM(1, 2, 3, 4)         --> 10
  AVERAGE(10, 20, 30)     --> 20


3.5. COMBINATORICS
--------------------------------------------------------------------------------

  NCR(n, k) or COMB(n, k) or C(n, k)
  - Calculates combinations ("n choose k").

  NPR(n, k) or PERM(n, k) or P(n, k)
  - Calculates permutations.

Samples:
  NCR(5, 2)               --> 10
  NPR(5, 2)               --> 20


3.6. CONVERSION & MEMORY FUNCTIONS
--------------------------------------------------------------------------------

--- Angle Conversion ---
  DEGREES(radians)  - Converts radians to degrees
  RADIANS(degrees)  - Converts degrees to radians

--- Base Conversion (Return a String Result) ---
  These functions return a string prefixed with "RES:".
  HEX(n)            - Converts integer n to a hexadecimal string (e.g., "&HA")
  OCT(n)            - Converts integer n to an octal string (e.g., "&O12")
  BIN(n)            - Converts integer n to a binary string (e.g., "&B1010")

--- Memory ---
  MEM(key)          - Reads a numeric value from an external key-value store.
                      Returns 0 if the key does not exist.


================================================================================
PART 4: Advanced Features: Unit Conversions & Bitwise Logic
================================================================================

4.1. UNIT CONVERSIONS
--------------------------------------------------------------------------------

The evaluator has a powerful unit conversion system that works like a postfix
operator. You provide a number and then the conversion name. An optional '*'
can be used for clarity but is not required.

Syntax:
  <value> <ConversionName>
  <value> * <ConversionName>

Samples:
  100 Celsius_TO_Fahrenheit   --> 212
  5 * Mile_TO_kilometer       --> 8.04672
  (10+2) Foot_TO_inch         --> 144

--- Available Conversions (and their inverses) ---
- Length:
  Foot_TO_meter, Inch_TO_centimeter, Kilometer_TO_mile, Inch_TO_foot,
  Yard_TO_meter, Fathom_TO_meter, Mile_TO_light-year, Parsec_TO_light-year
- Area:
  Square_ft_TO_square_m, Square_in_TO_square_cm, Hectare_TO_acre
- Mass:
  Pound_TO_kilogram, Ton_(metric)_TO_Kilogram, Ton_(US)_TO_Kilogram,
  Ton_(UK)_TO_Kilogram, Ounce_(avoirdupois)_TO_gram, Ounce_(troy)_TO_gram
- Temperature:
  Fahrenheit_TO_Celsius, Celsius_TO_Fahrenheit, Celsius_TO_Kelvin,
  Kelvin_TO_Celsius
- Volume:
  Gallon_(US_dry)_TO_liter, Gallon_(US_liquid)_TO_liter,
  Quart_(US_dry)_TO_gallon_(US_dry), Pint_TO_liter_(US_dry),
  Pint_TO_liter_(US_liquid), Cubic_ft_TO_cubic_m
- Power:
  Horsepower_(elec.)_TO_watt, Horsepower_(metric)_TO_watt,
  BTU/hour_TO_watt, Kilowatt_TO_watt
- Speed:
  Kph_TO_mph, Knot_TO_mph, Meter/sec_TO_ft/sec
- Time:
  Second_TO_minute, Minute_TO_hour, Minute_TO_day, Day_TO_hour
- Pressure:
  Psi_TO_pascal, Psi_TO_atmosphere, Psi_TO_kg/sqcm
- Angles:
  Degrees_TO_radians, Radians_TO_degrees


4.2. BITWISE OPERATIONS
--------------------------------------------------------------------------------

The evaluator provides two distinct systems for bitwise operations.

--- A) Numeric Bitwise Shifts ---
These functions operate on standard 64-bit signed integers and return a
numeric result. Arguments must be integers.

  SHL(value, bits)      - Logical Shift Left
  SHR(value, bits)      - Logical Shift Right (zeros shifted in)
  SAR(value, bits)      - Arithmetic Shift Right (sign bit is preserved)

Samples:
  SHL(&HFF, 8)            --> 65280  (&HFF00)
  SAR(-16, 2)             --> -4


--- B) String-Based Bitwise Logic ---
This is a more powerful system that performs bitwise logic on numbers of
arbitrary size.
- **Arguments:** Can be decimal, &H, &B, &O literals, or any nested expression.
- **Result:** These functions ALWAYS return a string result (e.g., "RES:&HCAFE"),
  which is an uppercase hexadecimal number with a prefix. This result can
  be used in subsequent string-based bitwise operations.

This system can be invoked only as top-level functions (e.g., `BITAND(&HFO, &H0F)`).
Because they return a String-Result, they are implemented in a Fast-Path.
They can not be used inside standard functions within a larger expression
like: (e.g., `1 + SQR(BITAND(...))`). This is not supported; 
these functions are either top-level or result in a final string answer.    

The numeric bitwise functions inside `Eval` are different.

  BITAND(x, y)      - Bitwise AND
  BITOR(x, y)       - Bitwise OR
  BITXOR(x, y)      - Bitwise XOR
  BITNOT(x)         - Bitwise NOT (one's complement)
  ROL(value, bits)  - Rotate Left
  ROR(value, bits)  - Rotate Right

--- Bit Lane / Width ---
By default, these string-based operations work on a 64-bit lane.
This can be controlled programmatically via `Eval_Bit()` or `Eval_SetBitLane()`.
- For BITNOT, ROL, ROR: The width is determined by the `bit lane` setting.
- For BITAND, BITOR, BITXOR: The width is the maximum of the two operands'
  widths, or the `bit lane` if it is set larger.

Samples:
  BITAND(&HF0F0, &HFFFF)   --> "RES:F0F0"
  BITOR(&HFO, &H0F)       --> "RES:FF"
  BITNOT(&HFF)            --> "RES:FFFFFFFFFFFFFF00" (on a 64-bit lane)
  ROL(&H1234, 4)          --> "RES:2341" (within a 16-bit width of the operand)
  BITAND(10, 12)          --> "RES:8" (10=&B1010, 12=&B1100)
  BITAND(MEM(1), &HFF)    --> (evaluates MEM(1) first, then performs AND)

--- END OF MANUAL ---
```